<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
<head>
    <title>Cygwin/X - Reporting X server crashes</title>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <link rel="stylesheet" type="text/css" href="../cygx.css" />
    <link rel="icon" type="image/ico" href="../favicon.ico" />
</head>

<body>
    <!--#include virtual="../cygx-header.html" -->
    <h1>Reporting X server crashes</h1>

    <p>Useful backtraces will help identify where and why the crash is
    occurring, which will help us fix the bug.</p>

    <h2>Automatically reporting crashes</h2>

    <ul>
      <li>Install the <b>xorg-server-cygwin-crashreporter</b> package</li>
      <li>Reproduce your crash</li>
    </ul>

    <p>This should automatically start a crash reporter, which will generate and
    upload a minidump file containing information about the crash.</p>

    <p>In some cases, this doesn't work (for reasons still under investigation),
    in which case see the following section.</p>

    <h2>Manually producing a crash backtrace</h2>

    <p>To generate a useful backtrace, you will need debugging symbols for the X server.</p>

    <h3>Preparation</h3>
    <br/>
    <ul>
      <li>Install the <b>xorg-server-debuginfo</b> package (for debugging symbols)</li>
      <li>Install the <b>gdb</b> package (for <tt>gdb</tt>)</li>
      <li>Install the <b>sysvinit</b> package (for <tt>pidof</tt>)</li>
    </ul>

    <h3>Generating a backtrace when some specific action is making the X server crash (automatically)</h3>
    <br/>
    <ul>
     <li>Start XWin using your normal method</li>
     <li>Reproduce your crash</li>
     <li>A backtrace should be captured into /var/log/xwin/XWin.0.log</li>
    </ul>

    <h3>Generating a backtrace when some specific action is making the X server crash (manually)</h3>
    <br/>
    <ul>
     <li>Start XWin using your normal method</li>
     <li>In a non-X terminal window, run <tt>gdb --pid=`pidof /usr/bin/XWin`</tt>, to attach gdb to the running X server</li>
     <li>Type <tt>c</tt> at the <tt>(gdb)</tt> prompt, to resume running the X server</li>
     <li>Reproduce your crash</li>
     <li>Type <tt>bt full</tt> at the <tt>(gdb)</tt> prompt, to produce a backtrace</li>
    </ul>

    <h3>Generating a backtrace when the X server is crashing at startup</h3>
    <br/>
    <ul>
     <li>In a non-X terminal window, run <tt>gdb --args /usr/bin/XWin -multiwindow</tt>, to start the X server under gdb
     (If you have customized how you start XWin to add additional options, you should also add them here)</li>
     <li>Type <tt>handle SIGSYS nostop</tt> at the <tt>(gdb)</tt> prompt</li>
     <li>Type <tt>r</tt> at the <tt>(gdb)</tt> prompt, to start running the X server</li>
     <li>Your crash should occur</li>
     <li>Type <tt>bt full</tt> at the <tt>(gdb)</tt> prompt, to produce a backtrace</li>
    </ul>

    <h3>Generating a backtrace when the X server is crashing at startup (alternative approach using JIT debugging)</h3>
    <br/>
    <ul>
     <li>Set the error_start token in the CYGWIN environment variable to run gdb, e.g. <tt>CYGWIN="error_start=C:\cygwin\bin\gdb"</tt>
         (If you are going to start the X server using a Windows shortcut, you will have to set this in the System applet of the Windows control panel)</li>
     <li>Start XWin using your normal method</li>
     <li>Your crash should occur</li>
     <li>Type <tt>bt full</tt> at the <tt>(gdb)</tt> prompt, to produce a backtrace</li>
    </ul>

    <p>Please attach the output from gdb, in addition to your <tt>/var/log/xwin/XWin.0.log</tt>, to your problem report.</p>

    <h3>Cleaning up</h3>
    <br/>
    <ul>
      <li>Uninstall the <b>xorg-server-debuginfo</b> package</li>
      <li>Uninstall the <b>gdb</b> and <b>sysvinit</b> packages if you no longer need them</li>
      <li>Restore the previous value of the CYGWIN environment variable, if you changed it</li>
    </ul>

    <h3>Preparation (alternative approach)</h3>
    <br/>
    <p>Alternatively, X server snapshots are built with debugging symbols included. You can install an X server snapshot with the following steps:</p>
    <ul>
      <li>
        Download the latest X Server snapshot from <a href="ftp://cygwin.com/pub/cygwinx/">ftp://cygwin.com/pub/cygwinx</a>
        <br/>
        <tt>wget ftp://cygwin.com/pub/cygwinx/XWin.YYYMMDD-git-XXXXXXXXXXXXXXXX.exe.bz2</tt>
      </li>
      <li>
        Uncompress it
        <br/>
        <tt>bunzip2 XWin.YYYMMDD-git-XXXXXXXXXXXXXXXX.exe.bz2</tt>
      </li>
      <li>
        Ensure it is executable
        <br/>
        <tt>chmod +x XWin.YYYMMDD-git-XXXXXXXXXXXXXXXX.exe</tt>
      </li>
      <li>
        Move it to /usr/bin
        <br/>
        <tt>mv XWin.YYYMMDD-git-XXXXXXXXXXXXXXXX.exe /usr/bin/XWin.exe</tt>
      </li>
    </ul>

    <p>To remove the X server snapshot, use setup.exe to reinstall the <b>xorg-server</b> package</p>

    <!--#include virtual="../cygx-footer.html" -->
</body>
</html>
